Skip to content

Conversation

gladjohn
Copy link
Contributor

Updated the document to reflect changes from 'Short-Lived Credential (SLC)' to 'Certificate' terminology and clarified the handling of certificate revocation scenarios.

Fixes - Spec update

Changes proposed in this request
This pull request updates the documentation for MSI V2 credential revocation, clarifying and expanding the specification to focus on certificate revocation (rather than short-lived credentials) and aligning terminology, flows, error handling, and acceptance tests with current implementation and Azure AD error codes. The changes provide detailed guidance on how MSAL should handle certificate revocation, claims challenges, and telemetry.

Key documentation improvements:

Terminology and Flow Updates:

  • Changed terminology throughout from "Short-Lived Credential (SLC)" to "certificate," clarifying that the revocation and renewal process is certificate-based. Sequence diagrams and flow descriptions are updated for accuracy. [1] [2]

Error Handling and Remediation:

  • Added explicit mapping of AADSTS error codes (1000610–1000614) to certificate/attestation failures and detailed required MSAL remediation steps, including bypassing the cache and minting a new certificate.
  • Provided updated pseudo-code and acceptance tests to reflect these flows, emphasizing auto-remediation and claims challenge handling.

Claims Challenge Handling:

  • Clarified the process for handling claims challenges: when an application receives a 401 with claims, it must pass the claims to MSAL, which then mints a new certificate and retries the token request with the claims.

Acceptance Tests and Telemetry:

  • Revised acceptance test scenarios to match the new flows, including auto-remediation, claims challenges, and telemetry validation.
  • Updated telemetry documentation for MsalMsiCounter to reflect the new tags and expected values for improved diagnostics.

Testing
n/a

Performance impact
n/a

Documentation
n/a

Updated the document to reflect changes from 'Short-Lived Credential (SLC)' to 'Certificate' terminology and clarified the handling of certificate revocation scenarios.
@gladjohn gladjohn requested a review from a team as a code owner September 23, 2025 23:37
Copy link
Member

@bgavrilMS bgavrilMS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved with comments

Copy link
Member

@bgavrilMS bgavrilMS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about telemetry. Maybe start with having those values logged. Let's focus more on server telemetry.

@gladjohn gladjohn requested a review from bgavrilMS September 25, 2025 00:11
| **AADSTS1000610–14 Auto-Remediation (Retry Fails)** | Same initial condition as above. New cert minted, retry still fails deterministically (e.g., repeated same code). | Failure surfaced after retry. (`CredentialOutcome=Retry Failed`) |
| **Unspecified Credential Issue** | eSTS returns `invalid_client` without codes. MSAL forces new certificate and retries. | Token succeeds or failure surfaced (assert correct `CredentialOutcome`). |
| **Claims Challenge Path** | Resource 401 with claims; app supplies claims; MSAL re-mints cert (`bypass_cache=true`) and retries with claims. | New token with claims. (`CredentialOutcome=Success`) |
| **IMDS/IssueCredential Failure Path** | `/issuecredential` call fails (network / service / malformed). | Failure returned; no infinite retry. (`CredentialOutcome=Retry Failed` if after a retry attempt) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

specify which retry policy

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure I follow this comment

Updated revocation scenarios and clarified certificate request process.
@@ -0,0 +1,196 @@
# Certificate Revocation Specification
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this going to be implemented for preview?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, this is not for preview.

@gladjohn gladjohn requested a review from bgavrilMS October 22, 2025 13:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants